home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Skunkware 5
/
Skunkware 5.iso
/
man
/
cat.3
/
GetBitmap.3
< prev
next >
Wrap
Text File
|
1995-07-25
|
17KB
|
331 lines
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333)))) TTTTkkkk (((( )))) TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333))))
_________________________________________________________________
NNNNAAAAMMMMEEEE
Tk_GetBitmap, Tk_DefineBitmap, Tk_NameOfBitmap,
Tk_SizeOfBitmap, Tk_FreeBitmap, Tk_GetBitmapFromData -
maintain database of single-plane pixmaps
SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
####iiiinnnncccclllluuuuddddeeee <<<<ttttkkkk....hhhh>>>>
Pixmap
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((_i_n_t_e_r_p, _t_k_w_i_n, _i_d))))
int |
TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp((((_i_n_t_e_r_p, _n_a_m_e_I_d, _s_o_u_r_c_e, _w_i_d_t_h, _h_e_i_g_h_t) |
Tk_Uid
TTTTkkkk____NNNNaaaammmmeeeeOOOOffffBBBBiiiittttmmmmaaaapppp((((_d_i_s_p_l_a_y, _b_i_t_m_a_p)))) |
TTTTkkkk____SSSSiiiizzzzeeeeOOOOffffBBBBiiiittttmmmmaaaapppp((((_d_i_s_p_l_a_y, _b_i_t_m_a_p, _w_i_d_t_h_P_t_r, _h_e_i_g_h_t_P_t_r)))) |
TTTTkkkk____FFFFrrrreeeeeeeeBBBBiiiittttmmmmaaaapppp((((_d_i_s_p_l_a_y, _b_i_t_m_a_p)))) |
AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
Tcl_Interp *_i_n_t_e_r_p (in) Interpreter to use for
error reporting.
Tk_Window _t_k_w_i_n (in) Token for window in
which the bitmap will
be used.
Tk_Uid _i_d (in) Description of bitmap;
see below for possible
values.
Tk_Uid *_n_a_m_e_I_d (in) Name for new bitmap to
be defined.
char *_s_o_u_r_c_e (in) Data for bitmap, in
standard bitmap
format. Must be
stored in static
memory whose value
will never change.
unsigned int _w_i_d_t_h (in) Width of bitmap.
unsigned int _h_e_i_g_h_t (in) Height of bitmap.
unsigned int *_w_i_d_t_h_P_t_r (out) Pointer to word to
fill in with _b_i_t_m_a_p's
width.
Page 1 (printed 7/23/95)
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333)))) TTTTkkkk (((( )))) TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333))))
unsigned int *_h_e_i_g_h_t_P_t_r (out) Pointer to word to
fill in with _b_i_t_m_a_p's
height.
Display *_d_i_s_p_l_a_y (in) Display for which
_b_i_t_m_a_p was allocated. |
Pixmap _b_i_t_m_a_p (in) Identifier for a
bitmap allocated by
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp.
_________________________________________________________________
DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
These procedures manage a collection of bitmaps (one-plane
pixmaps) being used by an application. The procedures allow
bitmaps to be re-used efficiently, thereby avoiding server
overhead, and also allow bitmaps to be named with character
strings.
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp takes as argument a Tk_Uid describing a bitmap.
It returns a Pixmap identifier for a bitmap corresponding to
the description. It re-uses an existing bitmap, if
possible, and creates a new one otherwise. At present, _i_d
must have one of the following forms:
@@@@_f_i_l_e_N_a_m_e _F_i_l_e_N_a_m_e must be the name of a file
containing a bitmap description in the
standard X11 or X10 format.
_n_a_m_e _N_a_m_e must be the name of a bitmap
defined previously with a call to
TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp. The following names
are pre-defined by Tk:
eeeerrrrrrrroooorrrr The international "don't" |
symbol: a circle with a |
diagonal line across it.
ggggrrrraaaayyyy55550000 50% gray: a checkerboard
pattern where every other
bit is on.
ggggrrrraaaayyyy22225555 25% gray: a pattern where
25% of the bits are on,
consisting of all the bit
positions that can be
reached by a chess knight
starting at (0,0).
hhhhoooouuuurrrrggggllllaaaassssssss An hourglass symbol. |
Page 2 (printed 7/23/95)
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333)))) TTTTkkkk (((( )))) TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333))))
iiiinnnnffffoooo ||
A large letter ``i''. |
qqqquuuueeeesssstttthhhheeeeaaaadddd ||
The silhouette of a human |
head, with a question mark |
in it. |
qqqquuuueeeessssttttiiiioooonnnn ||
A large question-mark. |
wwwwaaaarrrrnnnniiiinnnngggg ||
A large exclamation point.
Under normal conditions, TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp returns an identifier
for the requested bitmap. If an error occurs in creating
the bitmap, such as when _i_d refers to a non-existent file,
then NNNNoooonnnneeee is returned and an error message is left in
_i_n_t_e_r_p->_r_e_s_u_l_t.
TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp associates a name with in-memory bitmap data |
so that the name can be used in later calls to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp. |
The _n_a_m_e_I_d argument gives a name for the bitmap; it must |
not previously have been used in a call to TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp. |
The arguments _s_o_u_r_c_e, _w_i_d_t_h, and _h_e_i_g_h_t describe the bitmap. |
TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp normally returns TCL_OK; if an error occurs |
(e.g. a bitmap named _n_a_m_e_I_d has already been defined) then |
TCL_ERROR is returned and an error message is left in |
_i_n_t_e_r_p->_r_e_s_u_l_t. Note: TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp expects the memory |
pointed to by _s_o_u_r_c_e to be static: TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp doesn't |
make a private copy of this memory, but uses the bytes |
pointed to by _s_o_u_r_c_e later in calls to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp.
Typically TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp is used by ####iiiinnnncccclllluuuuddddeeee-ing a bitmap
file directly into a C program and then referencing the
variables defined by the file. For example, suppose there
exists a file ssssttttiiiipppp....bbbbiiiittttmmmmaaaapppp, which was created by the bbbbiiiittttmmmmaaaapppp
program and contains a stipple pattern. The following code
uses TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp to define a new bitmap named ffffoooooooo:
Pixmap bitmap;
#include "stip.bitmap"
Tk_DefineBitmap(interp, Tk_GetUid("foo"), stip_bits,
stip_width, stip_height);
...
bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("foo"));
This code causes the bitmap file to be read at compile-time
and incorporates the bitmap information into the program's
executable image. The same bitmap file could be read at
run-time using TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp:
Pixmap bitmap;
bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("@stip.bitmap"));
Page 3 (printed 7/23/95)
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333)))) TTTTkkkk (((( )))) TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333))))
The second form is a bit more flexible (the file could be
modified after the program has been compiled, or a different
string could be provided to read a different file), but it
is a little slower and requires the bitmap file to exist
separately from the program.
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp maintains a database of all the bitmaps that
have been created. Whenever possible, it will return an
existing bitmap rather than creating a new one. This
approach can substantially reduce server overhead, so
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp should generally be used in preference to Xlib
procedures like XXXXRRRReeeeaaaaddddBBBBiiiittttmmmmaaaappppFFFFiiiilllleeee.
The bitmaps returned by TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp are shared, so callers
should never modify them. If a bitmap must be modified
dynamically, then it should be created by calling Xlib
procedures such as XXXXRRRReeeeaaaaddddBBBBiiiittttmmmmaaaappppFFFFiiiilllleeee or XXXXCCCCrrrreeeeaaaatttteeeePPPPiiiixxxxmmmmaaaapppp
directly.
The procedure TTTTkkkk____NNNNaaaammmmeeeeOOOOffffBBBBiiiittttmmmmaaaapppp is roughly the inverse of
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp. Given an X Pixmap argument, it returns the _i_d
that was passed to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp when the bitmap was created. |
_B_i_t_m_a_p must have been the return value from a previous call |
to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp.
TTTTkkkk____SSSSiiiizzzzeeeeOOOOffffBBBBiiiittttmmmmaaaapppp returns the dimensions of its _b_i_t_m_a_p |
argument in the words pointed to by the _w_i_d_t_h_P_t_r and |
_h_e_i_g_h_t_P_t_r arguments. As with TTTTkkkk____NNNNaaaammmmeeeeOOOOffffBBBBiiiittttmmmmaaaapppp, _b_i_t_m_a_p must |
have been created by TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp.
When a bitmap returned by TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp is no longer needed,
TTTTkkkk____FFFFrrrreeeeeeeeBBBBiiiittttmmmmaaaapppp should be called to release it. There should
be exactly one call to TTTTkkkk____FFFFrrrreeeeeeeeBBBBiiiittttmmmmaaaapppp for each call to
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp. When a bitmap is no longer in use anywhere
(i.e. it has been freed as many times as it has been gotten)
TTTTkkkk____FFFFrrrreeeeeeeeBBBBiiiittttmmmmaaaapppp will release it to the X server and delete it
from the database.
BBBBUUUUGGGGSSSS
In determining whether an existing bitmap can be used to
satisfy a new request, TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp considers only the
immediate value of its _i_d argument. For example, when a
file name is passed to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp, TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp will
assume it is safe to re-use an existing bitmap created from
the same file name: it will not check to see whether the
file itself has changed, or whether the current directory
has changed, thereby causing the name to refer to a
different file.
KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
PPPPaaaaggggeeee 4444 ((((pppprrrriiiinnnntttteeeedddd 7777////22223333////99995555))))
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333)))) TTTTkkkk (((( )))) TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333))))
bitmap, pixmap
Page 5 (printed 7/23/95)
